home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / psion / intr_sdk.txt < prev    next >
Text File  |  1994-05-13  |  14KB  |  322 lines
  1. 1.  Overview of the Series 3 Development Environments
  2.  
  3. Series 3 applications may be developed either in OPL or in
  4. 'C'.  The facilities available in both languages are such
  5. that, whichever language is used, there is often no great
  6. difference in terms of the appearance of the application to
  7. the user.
  8.  
  9. Generally speaking, an application written in 'C' will be
  10. more responsive and may use less memory than one written in
  11. OPL.  Large applications, or those that are critically
  12. dependent on speed will benefit from being written in 'C',
  13. which provides the potential to create a more sophisticated
  14. application than is practical in OPL.  In particular OPL has
  15. no special debugging facilities.  For many applications,
  16. however, the difference may not be significant.  Development
  17. in OPL involves a much smaller learning curve, particularly
  18. if the programmer is not already familiar with the 'C'
  19. language.
  20.  
  21. 1.1 OPL Development
  22.  
  23. Although it is possible to develop OPL programs on the
  24. Series 3 itself, this is impractical for most non-trivial
  25. applications.  To develop an application in OPL you will
  26. therefore need:
  27. - a Series 3 and its programming manual,
  28. - an IBM PC or compatible,
  29. - a text or program editor, such as Brief, to run on the PC,
  30. - a IBM PC version of the Psion Serial 3Link product.
  31. - optionally but highly recommended, the Psion 'C' Software
  32. Development Kit (SDK) Documentation.
  33.  
  34. Full documentation of OPL is contained in the Series 3
  35. Programming Manual, supplied with all Series 3 machines.
  36. The 'C' SDK contains much material of a general nature that
  37. will be of use to an OPL programmer.  There is a close
  38. parallel between the actions of OPL keywords and facilities
  39. provided for programming in 'C'.  In addition to providing
  40. more detailed information about such actions, it will be of
  41. particular interest to those who wish to:
  42. - Make use of the asynchronous I/O services by means of the
  43. IOA, IOWAIT, IOWAITSTAT, IOSIGNAL, KEYA, and KEYC keywords.
  44. Using these can greatly improve the responsiveness of a
  45. program - the techniques involved are extensively described,
  46. notably in the PLIB Reference and the I/O Devices References
  47. manuals,
  48. - access the EPOC Operating System services via the OPL CALL
  49. and OS mechanisms that can greatly extend the capabilities
  50. of an OPL program.  These services are fully described in
  51. the EPOC O/S System Services manual.
  52. In addition to these manuals, the basic Series 3 OPL
  53. development environment on the PC consists of a program
  54. editor, the OPL program translator HHTRAN.EXE (provided,
  55. together with an explanatory text file, as part of the 3Link
  56. software) and the resource compiler RCOMP.EXE.
  57. Using this development environment, the program can be
  58. written and translated on the PC.  The program is then
  59. transferred, via 3Link, to a Series 3 for testing.
  60.  
  61. 1.2 'C' Development
  62.  
  63. An application written in 'C' must be developed on a PC.
  64. For such development you will need:
  65. - a Series 3,
  66. - An IBM PC or compatible,
  67. - a text or program editor, such as Brief, to run the PC,
  68. - the IBM PC version of the Psion Serial 3Link product,
  69. - the Psion SDK Standard version which includes the TopSpeed
  70. C compiler (see section 1.2.1),
  71.  
  72. Developing in 'C'
  73. Programs are written on the PC using either the TopSpeed
  74. Environment or another program editor, such as Brief.  When
  75. successfully compiled and linked the program is transferred
  76. to and run on the Series 3, normally with the aid of the
  77. SIBO debugger that is provided with SDK.
  78. Those parts of the software that do not depend on the user
  79. interface code specific to the Series 3 may be debugged
  80. locally on the PC.
  81.  
  82. Why TopSpeed 'C'?
  83. TopSpeed 'C' was developed by Jensen & Partners Int. (JPI)
  84. and is now owned by Clarion Inc.  Psion use this less usual
  85. 'C' because in does pure small model (the ES register is
  86. never corrupted) and because, thanks to its flexible calling
  87. conventions, it produces code 10-15% smaller than most 'C'
  88. compilers.
  89.  
  90. SIBO is the name given to Psion's hardware architecture
  91. common to the Series 3 and HC ranges.  EPOC is the name of
  92. the operating system.
  93.  
  94. 1.2.1 The Psion Software Development Kit
  95.  
  96. The Psion 'C' SDK provides the information necessary to
  97. develop 'C' language applications for Psion SIBO based
  98. Products.
  99. The SDK is available in three flavours: Documentation,
  100. Standard and Professional.
  101.  
  102. Psion 'C' SDK Documentation (part number 1505-0014 01)
  103.  
  104. The Documentation contains:
  105. - three volumes, divided into fourteen manuals,
  106. - the Psion software environment, including libraries,
  107. header files and associated software tools,
  108. - includes the Object Oriented Programming (OOP)
  109. documentation,
  110. - a range of example program source code that relates to the
  111. documentation.
  112. The version is not sufficient to develop SIBO applications
  113. in 'C'.  It is designed for developers who:
  114. - already have the TopSpeed 'C' Environment,
  115. - require additional copies of the documentation, say, for
  116. design purposes,
  117. - wish to evaluate the Psion SDK development environment,
  118. - intend to develop applications in OPL.
  119.  
  120. Psion 'C' SDK Standard (part number 1505-0013 01)
  121.  
  122. In addition to the material supplied in the Documentation
  123. version, the Standard version contains:
  124. - TopSpeed 'C' compiler and library,
  125. - TopSpeed Environment, a multi-window editor and project
  126. system.
  127. This version contains all the system software necessary to
  128. develop SIBO applications in 'C'.  The TopSpeed 'C'
  129. components may be used independently of the Psion SDK
  130. components both to learn 'C' programming and to write 'C'
  131. programs to run on a PC.
  132. This version is suitable for developers who:
  133. - intend to develop 'C' applications for any of the SIBO
  134. ranges of Psion computers,
  135. - do not already have the TopSpeed 'C' environment.
  136.  
  137. Psion 'C' SDK Professional (part number 1505-0012 01)
  138.  
  139. In addition to the material in the Standard version, the
  140. Professional version contains:
  141. - the TopSpeed TechKit, including the TopSpeed assembler,
  142. - the TopSpeed 'C' Library Source Kit, containing the source
  143. code (both 'C' and assembler) for the 'C' library that is
  144. supplied with the compiler,
  145. - Psion CLIB 'C' library source.
  146. This version is suitable for developers who:
  147. - wish, or need, to write at least part of the code in
  148. assembly language,
  149. - need to have control over the 'C' library.
  150.  
  151. Levels of programming:
  152. Programming level   Requirement                 Optional
  153. OPL                 Series 3/3a                 PC, Comms Link
  154. OPL + system calls  + SDK documentation         PC, Comms Link
  155. 'C'                 + SDK Standard, PC, Serial Link
  156. Advanced 'C'        + SDK Professional          
  157.  
  158. The 'C' libraries documented in SDK:
  159. CLIB 'C' Library    Easiest for porting existing 'C'
  160.                     programs (and programmers).  Restricted i/o.
  161. PLIB Psion Library  Extra library functions to utilise more
  162.                     of the features of the Series 3.
  163.                     Restricted i/o.  Generates much smaller
  164.                     code than CLIB because it is really
  165.                     just a layer over ROM code.
  166. HWIF Handheld Wimp  Gives access to dialogs, menus and edit
  167.      InterFace      boxes.  A 'C' layer over the object-
  168.      library        oriented HWIM.
  169. WLIB Psion Windows  Gives more flexibility when drawing to
  170.      Library        the screen.
  171.  
  172. The object-oriented libraries:
  173. HWIM Handheld        Called by HWIF.  Documented in SDK V2.0.
  174.      Windows Icons
  175.      and Menus
  176. OLIB Psion Object    Gives access to the built in objects.
  177.      Library         This gives an application full access
  178.                      to all facilities in the ROM.  eg multi-
  179.                      threaded programming.  Documented in
  180.                      SDK V2.0.
  181. FORM Formatted       For more complex edit boxes.  Not yet
  182.      text            documented.
  183.  
  184. These libraries can be mixed.  A professional application
  185. will generally not use CLIB.  They are ranked in order of
  186. accessibility.
  187.  
  188. 1.2.2 SDK 'C' documentation
  189.  
  190. The 'C' SDK documentation consists of fourteen manuals, in
  191. three volumes, covering a wide range of features of the SIBO
  192. architecture and development system.
  193.  
  194. General Programming Manual
  195. This manual explains how to install the SDK and how, by
  196. means of simple examples, to build an application that will
  197. run on a Psion SIBO machine.
  198. It describes in detail the differences between the CLIB and
  199. PLIB 'C' libraries and also gives guidance on copy
  200. protection.  The important Fundamental Programming
  201. Guidelines chapter explains the basic principles that should
  202. be understood by all developers of SIBO applications.  It
  203. includes advice on how to ensure that an application:
  204. - remains responsive to user input,
  205. - is robust against run-time errors, such as shortage of memory.
  206.  
  207. The SIBO Debugger
  208. The SIBO 'C' source-level debugger, supplied with all
  209. versions of the SDK, runs on a PC.  It is normally used for
  210. remote debugging of an application running on a SIBO machine
  211. but may, in some circumstances, also be used to debug SIBO
  212. applications running on the PC.
  213. The debugger is specifically designed to facilitate the
  214. debugging of applications running in the EPOC environment,
  215. in which the application's code segment may be relocated at
  216. any time.  This manual describes the facilities provided by
  217. the debugger and explains its use.
  218.  
  219. HC Programming Guide
  220. This manual contains information that is specific to the
  221. development of applications for the rugged and highly
  222. configurable HC range of hand-held computers.  The topics
  223. discussed include:
  224. - writing software for the HC,
  225. - the HC command Shell,
  226. - customising the HC ROM.
  227.  
  228. Series 3 Programming Guide
  229. This manual contains information that is specific to the
  230. Series 3 pocket computer.  The topics discussed include:
  231. - Series 3 Programming Overview - advice on writing multi-
  232. lingual applications,
  233. - communicating with the System Screen - including the
  234. differences between file-based and non-file based
  235. applications,
  236. - the receipt by applications of Shutdown and Switchfiles
  237. messages, and the modification of an application's behaviour
  238. by means of the technique of aliasing,
  239. - enhanced Sound Output.
  240.  
  241. Programming HWIF
  242. HWIF (the Hand-held Wimp InterFace) is a library of user
  243. interface routines suitable for use by 'C' developers
  244. producing applications for the Series 3 computer.  The HWIF
  245. library provides easy and efficient access to many aspects
  246. of Series 3 functionality, including sophisticated printing
  247. and the presentation of menu bars, dialog boxes and edit
  248. boxes.  The manual contains a range of worked examples as
  249. well as a comprehensive description of all HWIF routines.
  250.  
  251. Additional System Information
  252. The Additional System Information manual explains a variety
  253. of topics, including the MCLINK communications software
  254. (this forms part of the Psion serial 3Link product),
  255. resource files, printer drivers, the file formats used by
  256. applications and the writing of device drivers.
  257.  
  258. PLIB Reference
  259. This manual contains a comprehensive description of the PLIB
  260. 'C' function library.  The library routines are classified
  261. into fourteen areas of functionality and each group is
  262. accompanied by background information, usage recommendations
  263. and example code.
  264.  
  265. Window Server Reference
  266. This manual contains a description of the WLIB library.
  267. This library provides an interface to the window server
  268. built into each SIBO machine, supplying a range of
  269. sophisticated graphics operations.
  270. The topics discussed include:
  271. - windows,
  272. - graphics output,
  273. - keyboard input,
  274. - bitmaps,
  275. - text fonts.
  276. The descriptions are accompanied by example code.
  277.  
  278. I/O Devices Reference
  279. This manual describes the I/O device drivers that have been
  280. written by Psion.
  281. The description of each driver includes a full explanation
  282. of the services that it supports, together with example
  283. code.
  284.  
  285. ISAM Reference
  286. The ISAM Reference (Indexed Sequential Access Method)
  287. dynamic library provides a powerful set of functions to
  288. access record- and field- structured files of the type that
  289. are manipulated by OPL programs and the database
  290. applications on SIBO machines.
  291. The ISAM Reference manual explains, with the aid of example
  292. code, how to load and use the ISAM library, and contains a
  293. complete description of the ISAM functions.
  294.  
  295. EPOC O/S System Services
  296. This manual contains a complete description of the software
  297. interrupt interface to ROM-based system services, classified
  298. into 21 areas of functionality.
  299. An appendix lists the services both alphabetically, by
  300. service name, and numerically, by interrupt and function
  301. number.  This will be of particular interest to OPL and
  302. assembly language programmers.
  303.  
  304. Hardware Reference
  305. The Hardware Reference manual contains a description of the
  306. SIBO computer hardware, including the principal chip set,
  307. expansion ports and the SIBO serial protocol.
  308.  
  309. Object Oriented Programming Guide (applies to Series 3 Range
  310. only)
  311. This contains a description of classes, categories, objects,
  312. methods and property.  It explains how the built in objects
  313. may be used with a practical guide to using WIN, DLGBOX,
  314. LODGER and other classes under HWIM.
  315.  
  316. OLIB reference
  317. This has details of a numerous classes including: TIME,
  318. variable array classes (similar to container classes in
  319. C++), RSCFILE (Resource Files), CLEANUP, APPMAN (Application
  320. Manager), ACTIVE,  and TIMER.  It also describes the IPCS
  321. (Inter Process Communications Service) and Link Paste.
  322.